<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.ui.ListWidget</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_ui doc_api_ui_list_widget'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../../'>Howl 0.3 Documentation</a></li><li>Api</li><li>Ui</li><li>howl.ui.ListWidget</li></ol>
      <h1 id="howl.ui.listwidget">howl.ui.ListWidget</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.ui.ListWidget</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#constructor" class="toc-group-header constructor">Constructor</a>
<li class=""><a href="#listwidget">ListWidget </a></li>
</div>
<div class="toc-group">
<a href="#properties" class="toc-group-header properties">Properties</a>
<li class=""><a href="#.columns">.columns</a></li>
<li class=""><a href="#.items">.items</a></li>
<li class=""><a href="#.max_height">.max_height</a></li>
<li class=""><a href="#.min_height">.min_height</a></li>
<li class=""><a href="#.selected">.selected</a></li>
<li class=""><a href="#.showing">.showing</a></li>
</div>
<div class="toc-group">
<a href="#methods" class="toc-group-header methods">Methods</a>
<li class=""><a href="#hide">hide </a></li>
<li class=""><a href="#show">show </a></li>
<li class=""><a href="#update">update </a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>ListWidget is a widget containing a selection list. It displays a list of&#x000A;options with one option highlighted - the selected item. A ListWidget is&#x000A;primarily used to display a selection list attached to the <a href="command_line.html">command line</a>. For&#x000A;example, the <a href="../interact.html#select">interact.select</a> interaction uses the&#x000A;ListWidget to display a selection list.</p>&#x000A;&#x000A;<p>ListWidget handles keystrokes bound to the &lsquo;cursor-up&rsquo;, &lsquo;cursor-down&rsquo;,&#x000A;&lsquo;cursor-page-up&rsquo; and &lsquo;cursor-page-down&rsquo; commands to change the currently&#x000A;selected item. The default keystrokes bound to these commands are the <code>up</code>,&#x000A;<code>down</code> , <code>pgup</code> and <code>pgdn</code> keys respectively. This widget also provides an API&#x000A;to get the currently selected item and update the items in the list.</p>&#x000A;&#x000A;<hr>&#x000A;&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="command_line.html">CommandLine</a> API</li>&#x000A;<li>The <a href="../../spec/ui/list_widget_spec.html">spec</a> for ListWidget</li>&#x000A;<li>The <a href="../interact.html#select">interact.select</a> interaction which displays a&#x000A;selection list using ListWidget</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="constructor">Constructor</h2>&#x000A;&#x000A;<h3 id="listwidget">ListWidget <span class="arg-list">(matcher, opts={})</span></h3>&#x000A;&#x000A;<p>Creates a new ListWidget.</p>&#x000A;&#x000A;<ul>&#x000A;<li><p><code>matcher</code> is a function that accepts a string and returns an table. Each&#x000A;element in this table represents one select-able option and can be either a&#x000A;string for a single column list, or a table for a multiple column list. When&#x000A;each item is a table, it contains a list of strings, one each for each column.&#x000A;Instead of a string, a <a href="styled_text.html">StyledText</a> object can be used.</p>&#x000A;&#x000A;<p>The <code>matcher</code> is called on widget initialization and whenever the&#x000A;<a href="#update">update()</a> function is called. The <code>search_text</code> argument provided in&#x000A;<code>update()</code> is passed to the <code>matcher</code> and the displayed items are replaced with&#x000A;the new list of items returned from the <code>matcher</code>.</p></li>&#x000A;<li><p><code>opts</code> is a table of options which can contain the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>filler_text</code>: <em>[optional, default:&lsquo;~&rsquo;]</em> The text displayed to fill up extra&#x000A;space below the list of items, when the items take less space than the height of&#x000A;the widget.</li>&#x000A;<li><code>never_shrink</code>: <em>[optional, default:false]</em> When <code>true</code>, the height of the&#x000A;widget does not shrink even if the list is updated to contain fewer items that&#x000A;dont fill up the visible height. By default the height of the widget adjusts to&#x000A;fit the items list while staying within the constrains specified by <code>min_height</code>&#x000A;and <code>max_height</code>.</li>&#x000A;<li><code>on_selection_change</code>: <em>[optional]</em> A callback function that is invoked&#x000A;whenver the currently selected item changes. The callback is called with the&#x000A;newly selected item as the only argument.</li>&#x000A;<li><code>reverse</code>: <em>[optional, default:false]</em> When <code>true</code>, displays the items in&#x000A;reverse order, with the first item shown at the bottom and subsequent items&#x000A;above it.</li>&#x000A;</ul></li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="properties">Properties</h2>&#x000A;&#x000A;<h3 id=".columns">.columns</h3>&#x000A;&#x000A;<p>A table specifying a header and styles for each column. The schema of this table&#x000A;is identical to the <code>columns</code> argument in the&#x000A;<a href="styled_text.html#styledtext.for_table">StyledText.for_table</a> function.&#x000A;Read/write.</p>&#x000A;&#x000A;<h3 id=".items">.items</h3>&#x000A;&#x000A;<p>A table contining the items currently displayed. Read-only.</p>&#x000A;&#x000A;<h3 id=".max_height">.max_height</h3>&#x000A;&#x000A;<p>The maximum height for the widget, in pixels. The height is rounded down to the&#x000A;closest multiple of the line height. The widget is never taller than this&#x000A;height. If the items don&rsquo;t fit within the height, paging is enabled. Read/write.</p>&#x000A;&#x000A;<h3 id=".min_height">.min_height</h3>&#x000A;&#x000A;<p>The minimum height for the widget, in pixels. The height is rounded down to the&#x000A;closest multiple of the line height. The widget is never shorter than this&#x000A;height. If the items don&rsquo;t fill up the height, the filler text is displayed on&#x000A;each line to fill the extra space. Read/write.</p>&#x000A;&#x000A;<h3 id=".selected">.selected</h3>&#x000A;&#x000A;<p>The currently selected item. Read/write.</p>&#x000A;&#x000A;<h3 id=".showing">.showing</h3>&#x000A;&#x000A;<p><code>true</code> when the widget is currently showing or <code>false</code> when hidden. Read-only.</p>&#x000A;&#x000A;<h2 id="methods">Methods</h2>&#x000A;&#x000A;<h3 id="hide">hide <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Hides the widget.</p>&#x000A;&#x000A;<h3 id="show">show <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Shows the widget.</p>&#x000A;&#x000A;<h3 id="update">update <span class="arg-list">(search_text)</span></h3>&#x000A;&#x000A;<p>Updates the list of displayed items to the items returned by calling&#x000A;<code>matcher(search_text)</code>. See <code>matcher</code> in the <a href="#constructor">constructor</a> above.</p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2015
            <a class='alert-link' href='https://github.com/nilnor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
